Associates a theme-compliant color or pattern with the background of a window.

OSStatus SetThemeWindowBackground (
    WindowRef inWindow, 
    ThemeBrush inBrush, 
    Boolean inUpdate
);

inWindow

A value of type WindowPtr. Pass a pointer to the window for which to set the background.

inBrush

A value of type ThemeBrush. Pass a constant representing the pattern or color to which to set the window background; see “Theme Brush Constants” for descriptions of possible values.

inUpdate

A value of type Boolean. Pass true to invalidate the content region of the window and erase the window. If you pass false, the window background is set but no drawing occurs on screen.

function result

A result code. The result code appearanceBadBrushIndexErr indicates that the brush constant passed was not valid.

DISCUSSION

The SetThemeWindowBackground function sets the color or pattern to which the Window Manager erases the window background.

Because the constant in the inBrush parameter can represent a color or pattern, depending on the current theme, your application must save and restore the current drawing state of the graphics port around calls to SetThemeWindowBackground. Under Appearance Manager 1.1 and later, you can use the functions GetThemeDrawingState and SetThemeDrawingState to do this. Prior to Appearance Manager 1.1, you must save and restore the pnPixPat and bkPixPat fields of your graphics port when saving the text and background colors. Because patterns in the bkPixPat field override the background color of the window, call the QuickDraw function BackPat to set your background pattern to a normal white pattern. This ensures that you can use RGBBackColor to set your background color to white, call the QuickDraw function EraseRect, and get the expected results.

VERSION NOTES

This function is available with Appearance Manager 1.0 and later.

AVAILABILITY

Supported in Carbon. Available in Mac OS 8.1 and later when Carbon 1.0.2 or later is present.

© 2000 Apple Computer, Inc. — (Last Updated 5/8/2000)